home *** CD-ROM | disk | FTP | other *** search
/ Maclife 157 / MACLIFE157-2001-09.ISO.7z / MACLIFE157-2001-09.ISO / Linux / MacOS Tools / Other / BootX 1.1.3 (for Old Mac OS) / Sources / lib / From MoreFiles / Search.h < prev   
Text File  |  2001-07-23  |  9KB  |  247 lines
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    IndexedSearch and the PBCatSearch compatibility function.
  5. **
  6. **    by Jim Luther, Apple Developer Technical Support Emeritus
  7. **
  8. **    File:        Search.h
  9. **
  10. **    Copyright ｩ 1992-1998 Apple Computer, Inc.
  11. **    All rights reserved.
  12. **
  13. **    You may incorporate this sample code into your applications without
  14. **    restriction, though the sample code has been provided "AS IS" and the
  15. **    responsibility for its operation is 100% yours.  However, what you are
  16. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  17. **    after having made changes. If you're going to re-distribute the source,
  18. **    we require that you make it clear in the source that the code was
  19. **    descended from Apple Sample Code, but that you've made changes.
  20. */
  21.  
  22. #ifndef __SEARCH__
  23. #define __SEARCH__
  24.  
  25. #include <Types.h>
  26. #include <Files.h>
  27.  
  28. #include "Optimization.h"
  29.  
  30. #ifdef __cplusplus
  31. extern "C" {
  32. #endif
  33.  
  34. /*****************************************************************************/
  35.  
  36. pascal    OSErr    IndexedSearch(CSParamPtr pb,
  37.                               long dirID);
  38. /*    ｦ Search in and below a directory.
  39.     The IndexedSearch function performs an indexed search in and below the
  40.     specified directory using the same parameters (in pb) as is passed to
  41.     PBCatSearch. See Inside Macintosh: Files for a description of the
  42.     parameter block.
  43.     
  44.     pb            input:    A CSParamPtr record specifying the volume to search
  45.                         and the search criteria.
  46.                 output:    Fields in the parameter block are returned indicating
  47.                         the number of matches found, the matches, and if the
  48.                         search ended with noErr, the CatPosition record that
  49.                         lets you resume a search where the last search left
  50.                         off.
  51.     dirID        input:    The directory to search. If fsRtDirID is passed,
  52.                         the entire volume is searched.
  53.     
  54.     Note:    If you use a high-level debugger and use ioSearchTime to limit
  55.             the length of time to run the search, you'll want to step over
  56.             calls to IndexedSearch because it installs a Time Manager task.
  57.             Most high-level debuggers don't deal gracefully with interrupt
  58.             driven code.
  59.     
  60.     Result Codes
  61.         noErr                0        No error
  62.         nsvErr                -35        Volume not found
  63.         ioErr                -36        I/O error
  64.         eofErr                -39        End of catalog found (this is normal!)
  65.         paramErr            -50        Parameter block has invalid parameters
  66.                                     (see source for VerifyUserPB) or
  67.                                     invalid catPosition record was passed
  68.         extFSErr            -58        External file system error - no file
  69.                                     system claimed this call.
  70.         memFullErr            -108    Memory could not be allocated in heap
  71.         catChangedErr        -1304    Catalog has changed and catalog position
  72.                                     record may be invalid
  73.     
  74.     __________
  75.     
  76.     See also:    PBCatSearch, PBCatSearchSyncCompat
  77. */
  78.  
  79. /*****************************************************************************/
  80.  
  81. pascal    OSErr    PBCatSearchSyncCompat(CSParamPtr paramBlock);
  82. /*    ｦ Search a volume using PBCatSearch or IndexedSearch.
  83.     The PBCatSearchSyncCompat function uses PBCatSearch (if available) or
  84.     IndexedSearch (if PBCatSearch is not available) to search a volume
  85.     using a set of search criteria that you specify. It builds a list of all
  86.     files or directories that meet your specifications.
  87.     
  88.     pb            input:    A CSParamPtr record specifying the volume to search
  89.                         and the search criteria.
  90.                 output:    Fields in the parameter block are returned indicating
  91.                         the number of matches found, the matches, and if the
  92.                         search ended with noErr, the CatPosition record that
  93.                         lets you resume a search where the last search left
  94.                         off.
  95.     
  96.     Note:    If you use a high-level debugger and use ioSearchTime to limit
  97.             the length of time to run the search, you'll want to step over
  98.             calls to PBCatSearchSyncCompat because it calls IndexedSearch
  99.             which installs a Time Manager task. Most high-level debuggers
  100.             don't deal gracefully with interrupt driven code.
  101.     
  102.     Result Codes
  103.         noErr                0        No error
  104.         nsvErr                -35        Volume not found
  105.         ioErr                -36        I/O error
  106.         eofErr                -39        End of catalog found (this is normal!)
  107.         paramErr            -50        Parameter block has invalid parameters
  108.                                     (see source for VerifyUserPB) or
  109.                                     invalid catPosition record was passed
  110.         extFSErr            -58        External file system error - no file
  111.                                     system claimed this call.
  112.         memFullErr            -108    Memory could not be allocated in heap
  113.         catChangedErr        -1304    Catalog has changed and catalog position
  114.                                     record may be invalid
  115.         afpCatalogChanged    -5037    Catalog has changed and search cannot
  116.                                     be resumed
  117.     
  118.     __________
  119.     
  120.     See also:    PBCatSearch, IndexedSearch
  121. */
  122.  
  123. /*****************************************************************************/
  124.  
  125. pascal    OSErr    NameFileSearch(ConstStr255Param volName,
  126.                                short vRefNum,
  127.                                ConstStr255Param fileName,
  128.                                FSSpecPtr matches,
  129.                                long reqMatchCount,
  130.                                long *actMatchCount,
  131.                                Boolean newSearch,
  132.                                Boolean partial);
  133. /*    ｦ Search for files by file name with PBCatSearch.
  134.     The NameFileSearch function searches for files with a specific file
  135.     name on a volume that supports PBCatSearch.
  136.     Note: A result of catChangedErr means the catalog has changed between
  137.     searches, but the search can be continued with the possiblity that you
  138.     may miss some matches or get duplicate matches.  For all other results
  139.     (except for noErr), the search cannot be continued.
  140.  
  141.     volName            input:    A pointer to the name of a mounted volume
  142.                             or nil.
  143.     vRefNum            input:    Volume specification.
  144.     fileName        input:    The name of the file to search for.
  145.     matches            input:    Pointer to array of FSSpec where the match list is
  146.                             returned.
  147.     reqMatchCount    input:    Maximum number of matches to return    (the number of
  148.                             elements in the matches array).
  149.     actMatchCount    output: The number of matches actually returned.
  150.     newSearch        input:    If true, start a new search. If false and if
  151.                             vRefNum is the same as the last call to
  152.                             NameFileSearch, then start searching at the
  153.                             position where the last search left off.
  154.     partial            input:    If the partial parameter is false, then only files
  155.                             that exactly match fileName will be found.  If the
  156.                             partial parameter is true, then all file names that
  157.                             contain fileName will be found.
  158.     
  159.     Result Codes
  160.         noErr                0        No error
  161.         nsvErr                -35        Volume not found
  162.         ioErr                -36        I/O error
  163.         eofErr                -39        End of catalog found (this is normal!)
  164.         paramErr            -50        Parameter block has invalid parameters
  165.                                     (see source for VerifyUserPB) or
  166.                                     invalid catPosition record was passed
  167.         extFSErr            -58        External file system error - no file
  168.                                     system claimed this call.
  169.         memFullErr            -108    Memory could not be allocated in heap
  170.         catChangedErr        -1304    Catalog has changed and catalog position
  171.                                     record may be invalid
  172.         afpCatalogChanged    -5037    Catalog has changed and search cannot
  173.                                     be resumed
  174.     
  175.     __________
  176.     
  177.     Also see:    CreatorTypeFileSearch
  178. */
  179.  
  180. /*****************************************************************************/
  181.  
  182. pascal    OSErr    CreatorTypeFileSearch(ConstStr255Param volName,
  183.                                       short vRefNum,
  184.                                       OSType creator,
  185.                                       OSType fileType,
  186.                                       FSSpecPtr matches,
  187.                                       long reqMatchCount,
  188.                                       long *actMatchCount,
  189.                                       Boolean newSearch);
  190. /*    ｦ Search for files by creator/fileType with PBCatSearch.
  191.     The CreatorTypeFileSearch function searches for files with a specific
  192.     creator or fileType on a volume that supports PBCatSearch.
  193.     Note: A result of catChangedErr means the catalog has changed between
  194.     searches, but the search can be continued with the possiblity that you
  195.     may miss some matches or get duplicate matches.  For all other results
  196.     (except for noErr), the search cannot be continued.
  197.  
  198.     volName            input:    A pointer to the name of a mounted volume
  199.                             or nil.
  200.     vRefNum            input:    Volume specification.
  201.     creator            input:    The creator type of the file to search for.
  202.                             To ignore the creator type, pass 0x00000000 in
  203.                             this field.
  204.     fileType        input:    The file type of the file to search for.
  205.                             To ignore the file type, pass 0x00000000 in
  206.                             this field.
  207.     matches            input:    Pointer to array of FSSpec where the match list is
  208.                             returned.
  209.     reqMatchCount    input:    Maximum number of matches to return    (the number of
  210.                             elements in the matches array).
  211.     actMatchCount    output: The number of matches actually returned.
  212.     newSearch        input:    If true, start a new search. If false and if
  213.                             vRefNum is the same as the last call to
  214.                             CreatorTypeFileSearch, then start searching at the
  215.                             position where the last search left off.
  216.     
  217.     Result Codes
  218.         noErr                0        No error
  219.         nsvErr                -35        Volume not found
  220.         ioErr                -36        I/O error
  221.         eofErr                -39        End of catalog found (this is normal!)
  222.         paramErr            -50        Parameter block has invalid parameters
  223.                                     (see source for VerifyUserPB) or
  224.                                     invalid catPosition record was passed
  225.         extFSErr            -58        External file system error - no file
  226.                                     system claimed this call.
  227.         memFullErr            -108    Memory could not be allocated in heap
  228.         catChangedErr        -1304    Catalog has changed and catalog position
  229.                                     record may be invalid
  230.         afpCatalogChanged    -5037    Catalog has changed and search cannot
  231.                                     be resumed
  232.     
  233.     __________
  234.     
  235.     Also see:    NameFileSearch
  236. */
  237.  
  238. /*****************************************************************************/
  239.  
  240. #ifdef __cplusplus
  241. }
  242. #endif
  243.  
  244. #include "OptimizationEnd.h"
  245.  
  246. #endif    /* __SEARCH__ */
  247.